Profile of (eval 167)[JSON.pm:268]

Filename	(eval 167)[/usr/share/perl5/JSON.pm:268]
Statements	Executed 20 statements in 1.26ms
Eval Invoked At	/usr/share/perl5/JSON.pm line 268

Subroutines
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
1	1	1	19µs	19µs	JSON::Backend::XS::::init JSON::Backend::XS::init
1	1	1	17µs	51µs	JSON::Backend::XS::::BEGIN@9 JSON::Backend::XS::BEGIN@9
1	1	1	11µs	30µs	JSON::Backend::XS::::BEGIN@11 JSON::Backend::XS::BEGIN@11
1	1	1	11µs	17µs	JSON::Backend::XS::Supportable::BEGIN@99
1	1	1	11µs	16µs	JSON::Backend::XS::::BEGIN@42 JSON::Backend::XS::BEGIN@42
1	1	1	10µs	28µs	JSON::Backend::XS::::BEGIN@18 JSON::Backend::XS::BEGIN@18
1	1	1	10µs	18µs	JSON::Backend::XS::::BEGIN@29 JSON::Backend::XS::BEGIN@29
0	0	0	0s	0s	JSON::Backend::XS::Supportable::__ANON__[:110]
0	0	0	0s	0s	JSON::Backend::XS::Supportable::__ANON__[:114]
0	0	0	0s	0s	JSON::Backend::XS::Supportable::_decode
0	0	0	0s	0s	JSON::Backend::XS::Supportable::_encode
0	0	0	0s	0s	JSON::Backend::XS::Supportable::_incr_parse
0	0	0	0s	0s	JSON::Backend::XS::Supportable::_make_unsupported_method
0	0	0	0s	0s	JSON::Backend::XS::Supportable::_set_for_pp
0	0	0	0s	0s	JSON::Backend::XS::Supportable::decode_prefix
0	0	0	0s	0s	JSON::Backend::XS::Supportable::get_indent_length
0	0	0	0s	0s	JSON::Backend::XS::Supportable::indent_length
0	0	0	0s	0s	JSON::Backend::XS::::__ANON__[:32] JSON::Backend::XS::__ANON__[:32]
0	0	0	0s	0s	JSON::Backend::XS::::__ANON__[:33] JSON::Backend::XS::__ANON__[:33]
0	0	0	0s	0s	JSON::Backend::XS::::__ANON__[:63] JSON::Backend::XS::__ANON__[:63]
0	0	0	0s	0s	JSON::Backend::XS::::support_by_pp JSON::Backend::XS::support_by_pp

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Calls	Time in subs	Code
1
2
3					#
4					# Helper classes for Backend Module (XS)
5					#
6
7					package JSON::Backend::XS;
8
9	2	84µs	2	85µs	# spent 51µs (17+34) within JSON::Backend::XS::BEGIN@9 which was called: # once (17µs+34µs) by JSON::_load_xs at line 9 use constant INDENT_LENGTH_FLAG => 15 << 12; # spent 51µs making 1 call to JSON::Backend::XS::BEGIN@9 # spent 34µs making 1 call to constant::import
10
11	1	29µs	1	19µs	# spent 30µs (11+19) within JSON::Backend::XS::BEGIN@11 which was called: # once (11µs+19µs) by JSON::_load_xs at line 16 use constant UNSUPPORTED_ENCODE_FLAG => { # spent 19µs making 1 call to constant::import
12					ESCAPE_SLASH => 0x00000010,
13					ALLOW_BIGNUM => 0x00000020,
14					AS_NONBLESSED => 0x00000040,
15					EXPANDED => 0x10000000, # for developer's
16	1	31µs	1	30µs	}; # spent 30µs making 1 call to JSON::Backend::XS::BEGIN@11
17
18	1	27µs	1	18µs	# spent 28µs (10+18) within JSON::Backend::XS::BEGIN@18 which was called: # once (10µs+18µs) by JSON::_load_xs at line 24 use constant UNSUPPORTED_DECODE_FLAG => { # spent 18µs making 1 call to constant::import
19					LOOSE => 0x00000001,
20					ALLOW_BIGNUM => 0x00000002,
21					ALLOW_BAREKEY => 0x00000004,
22					ALLOW_SINGLEQUOTE => 0x00000008,
23					EXPANDED => 0x20000000, # for developer's
24	1	40µs	1	28µs	}; # spent 28µs making 1 call to JSON::Backend::XS::BEGIN@18
25
26
27					# spent 19µs within JSON::Backend::XS::init which was called: # once (19µs+0s) by JSON::_load_xs at line 269 of JSON.pm sub init {
28	1	2µs			local $^W;
29	2	133µs	2	26µs	# spent 18µs (10+8) within JSON::Backend::XS::BEGIN@29 which was called: # once (10µs+8µs) by JSON::_load_xs at line 29 no strict qw(refs); # spent 18µs making 1 call to JSON::Backend::XS::BEGIN@29 # spent 8µs making 1 call to strict::unimport
30	1	3µs			*{"JSON::decode_json"} = \&{"JSON::XS::decode_json"};
31	1	2µs			*{"JSON::encode_json"} = \&{"JSON::XS::encode_json"};
32	1	5µs			*{"JSON::XS::is_xs"} = sub { 1 };
33	1	6µs			*{"JSON::XS::is_pp"} = sub { 0 };
34	1	5µs			return 1;
35					}
36
37
38					sub support_by_pp {
39					my ($class, @methods) = @_;
40
41					local $^W;
42	2	351µs	2	21µs	# spent 16µs (11+5) within JSON::Backend::XS::BEGIN@42 which was called: # once (11µs+5µs) by JSON::_load_xs at line 42 no strict qw(refs); # spent 16µs making 1 call to JSON::Backend::XS::BEGIN@42 # spent 5µs making 1 call to strict::unimport
43
44					my $JSON_XS_encode_orignal = \&JSON::XS::encode;
45					my $JSON_XS_decode_orignal = \&JSON::XS::decode;
46					my $JSON_XS_incr_parse_orignal = \&JSON::XS::incr_parse;
47
48					*JSON::XS::decode = \&JSON::Backend::XS::Supportable::_decode;
49					*JSON::XS::encode = \&JSON::Backend::XS::Supportable::_encode;
50					*JSON::XS::incr_parse = \&JSON::Backend::XS::Supportable::_incr_parse;
51
52					*{JSON::XS::_original_decode} = $JSON_XS_decode_orignal;
53					*{JSON::XS::_original_encode} = $JSON_XS_encode_orignal;
54					*{JSON::XS::_original_incr_parse} = $JSON_XS_incr_parse_orignal;
55
56					push @JSON::Backend::XS::Supportable::ISA, 'JSON';
57
58					my $pkg = 'JSON::Backend::XS::Supportable';
59
60					*{JSON::new} = sub {
61					my $proto = JSON::XS->new; $$proto = 0;
62					bless $proto, $pkg;
63					};
64
65
66					for my $method (@methods) {
67					my $flag = uc($method);
68					my $type \|= (UNSUPPORTED_ENCODE_FLAG->{$flag} \|\| 0);
69					$type \|= (UNSUPPORTED_DECODE_FLAG->{$flag} \|\| 0);
70
71					next unless($type);
72
73					$pkg->_make_unsupported_method($method => $type);
74					}
75
76					push @{"JSON::XS::Boolean::ISA"}, qw(JSON::PP::Boolean);
77					push @{"JSON::PP::Boolean::ISA"}, qw(JSON::Boolean);
78
79					$JSON::DEBUG and Carp::carp("set -support_by_pp mode.");
80
81					return 1;
82					}
83
- -
87					#
88					# Helper classes for XS
89					#
90
91					package JSON::Backend::XS::Supportable;
92
93	1	3µs			$Carp::Internal{'JSON::Backend::XS::Supportable'} = 1;
94
95					sub _make_unsupported_method {
96					my ($pkg, $method, $type) = @_;
97
98					local $^W;
99	2	536µs	2	23µs	# spent 17µs (11+6) within JSON::Backend::XS::Supportable::BEGIN@99 which was called: # once (11µs+6µs) by JSON::_load_xs at line 99 no strict qw(refs); # spent 17µs making 1 call to JSON::Backend::XS::Supportable::BEGIN@99 # spent 6µs making 1 call to strict::unimport
100
101					*{"$pkg\::$method"} = sub {
102					local $^W;
103					if (defined $_[1] ? $_[1] : 1) {
104					${$_[0]} \|= $type;
105					}
106					else {
107					${$_[0]} &= ~$type;
108					}
109					$_[0];
110					};
111
112					*{"$pkg\::get_$method"} = sub {
113					${$_[0]} & $type ? 1 : '';
114					};
115
116					}
117
118
119					sub _set_for_pp {
120					JSON::_load_pp( $_INSTALL_ONLY );
121
122					my $type = shift;
123					my $pp = JSON::PP->new;
124					my $prop = $_[0]->property;
125
126					for my $name (keys %$prop) {
127					$pp->$name( $prop->{$name} ? $prop->{$name} : 0 );
128					}
129
130					my $unsupported = $type eq 'encode' ? JSON::Backend::XS::UNSUPPORTED_ENCODE_FLAG
131					: JSON::Backend::XS::UNSUPPORTED_DECODE_FLAG;
132					my $flags = ${$_[0]} \|\| 0;
133
134					for my $name (keys %$unsupported) {
135					next if ($name eq 'EXPANDED'); # for developer's
136					my $enable = ($flags & $unsupported->{$name}) ? 1 : 0;
137					my $method = lc $name;
138					$pp->$method($enable);
139					}
140
141					$pp->indent_length( $_[0]->get_indent_length );
142
143					return $pp;
144					}
145
146					sub _encode { # using with PP encode
147					if (${$_[0]}) {
148					_set_for_pp('encode' => @_)->encode($_[1]);
149					}
150					else {
151					$_[0]->_original_encode( $_[1] );
152					}
153					}
154
155
156					sub _decode { # if unsupported-flag is set, use PP
157					if (${$_[0]}) {
158					_set_for_pp('decode' => @_)->decode($_[1]);
159					}
160					else {
161					$_[0]->_original_decode( $_[1] );
162					}
163					}
164
165
166					sub decode_prefix { # if unsupported-flag is set, use PP
167					_set_for_pp('decode' => @_)->decode_prefix($_[1]);
168					}
169
170
171					sub _incr_parse {
172					if (${$_[0]}) {
173					_set_for_pp('decode' => @_)->incr_parse($_[1]);
174					}
175					else {
176					$_[0]->_original_incr_parse( $_[1] );
177					}
178					}
179
180
181					sub get_indent_length {
182					${$_[0]} << 4 >> 16;
183					}
184
185
186					sub indent_length {
187					my $length = $_[1];
188
189					if (!defined $length or $length > 15 or $length < 0) {
190					Carp::carp "The acceptable range of indent_length() is 0 to 15.";
191					}
192					else {
193					local $^W;
194					$length <<= 12;
195					${$_[0]} &= ~ JSON::Backend::XS::INDENT_LENGTH_FLAG;
196					${$_[0]} \|= $length;
197					*JSON::XS::encode = \&JSON::Backend::XS::Supportable::_encode;
198					}
199
200					$_[0];
201					}
202
203
204	1	4µs			1;
205					__END__
206
207					=head1 NAME
208
209					JSON - JSON (JavaScript Object Notation) encoder/decoder
210
211					=head1 SYNOPSIS
212
213					use JSON; # imports encode_json, decode_json, to_json and from_json.
214
215					# simple and fast interfaces (expect/generate UTF-8)
216
217					$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
218					$perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
219
220					# OO-interface
221
222					$json = JSON->new->allow_nonref;
223
224					$json_text = $json->encode( $perl_scalar );
225					$perl_scalar = $json->decode( $json_text );
226
227					$pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing
228
229					# If you want to use PP only support features, call with '-support_by_pp'
230					# When XS unsupported feature is enable, using PP (de\|en)code instead of XS ones.
231
232					use JSON -support_by_pp;
233
234					# option-acceptable interfaces (expect/generate UNICODE by default)
235
236					$json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } );
237					$perl_scalar = from_json( $json_text, { utf8 => 1 } );
238
239					# Between (en\|de)code_json and (to\|from)_json, if you want to write
240					# a code which communicates to an outer world (encoded in UTF-8),
241					# recommend to use (en\|de)code_json.
242
243					=head1 VERSION
244
245					2.59
246
247					This version is compatible with JSON::XS B<2.34> and later.
248
249
250					=head1 NOTE
251
252					JSON::PP was earlier included in the C<JSON> distribution, but
253					has since Perl 5.14 been a core module. For this reason,
254					L<JSON::PP> was removed from the JSON distribution and can now
255					be found also in the Perl5 repository at
256
257					=over
258
259					=item * L<http://perl5.git.perl.org/perl.git>
260
261					=back
262
263					(The newest JSON::PP version still exists in CPAN.)
264
265					Instead, the C<JSON> distribution will include JSON::backportPP
266					for backwards computability. JSON.pm should thus work as it did
267					before.
268
269					=head1 DESCRIPTION
270
271					************************ CAUTION ******************************
272					* This is 'JSON module version 2' and there are many differences *
273					* to version 1.xx *
274					* Please check your applications using old version. *
275					* See to 'INCOMPATIBLE CHANGES TO OLD VERSION' *
276					*******************************************************************
277
278					JSON (JavaScript Object Notation) is a simple data format.
279					See to L<http://www.json.org/> and C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>).
280
281					This module converts Perl data structures to JSON and vice versa using either
282					L<JSON::XS> or L<JSON::PP>.
283
284					JSON::XS is the fastest and most proper JSON module on CPAN which must be
285					compiled and installed in your environment.
286					JSON::PP is a pure-Perl module which is bundled in this distribution and
287					has a strong compatibility to JSON::XS.
288
289					This module try to use JSON::XS by default and fail to it, use JSON::PP instead.
290					So its features completely depend on JSON::XS or JSON::PP.
291
292					See to L<BACKEND MODULE DECISION>.
293
294					To distinguish the module name 'JSON' and the format type JSON,
295					the former is quoted by CE<lt>E<gt> (its results vary with your using media),
296					and the latter is left just as it is.
297
298					Module name : C<JSON>
299
300					Format type : JSON
301
302					=head2 FEATURES
303
304					=over
305
306					=item * correct unicode handling
307
308					This module (i.e. backend modules) knows how to handle Unicode, documents
309					how and when it does so, and even documents what "correct" means.
310
311					Even though there are limitations, this feature is available since Perl version 5.6.
312
313					JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or later), so in older versions
314					C<JSON> should call JSON::PP as the backend which can be used since Perl 5.005.
315
316					With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of a Perl side problem,
317					JSON::PP works slower in the versions. And in 5.005, the Unicode handling is not available.
318					See to L<JSON::PP/UNICODE HANDLING ON PERLS> for more information.
319
320					See also to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL>
321					and L<JSON::XS/ENCODING/CODESET_FLAG_NOTES>.
322
323
324					=item * round-trip integrity
325
326					When you serialise a perl data structure using only data types supported
327					by JSON and Perl, the deserialised data structure is identical on the Perl
328					level. (e.g. the string "2.0" doesn't suddenly become "2" just because
329					it looks like a number). There I<are> minor exceptions to this, read the
330					L</MAPPING> section below to learn about those.
331
332
333					=item * strict checking of JSON correctness
334
335					There is no guessing, no generating of illegal JSON texts by default,
336					and only JSON is accepted as input by default (the latter is a security
337					feature).
338
339					See to L<JSON::XS/FEATURES> and L<JSON::PP/FEATURES>.
340
341					=item * fast
342
343					This module returns a JSON::XS object itself if available.
344					Compared to other JSON modules and other serialisers such as Storable,
345					JSON::XS usually compares favorably in terms of speed, too.
346
347					If not available, C<JSON> returns a JSON::PP object instead of JSON::XS and
348					it is very slow as pure-Perl.
349
350					=item * simple to use
351
352					This module has both a simple functional interface as well as an
353					object oriented interface interface.
354
355					=item * reasonably versatile output formats
356
357					You can choose between the most compact guaranteed-single-line format possible
358					(nice for simple line-based protocols), a pure-ASCII format (for when your transport
359					is not 8-bit clean, still supports the whole Unicode range), or a pretty-printed
360					format (for when you want to read that stuff). Or you can combine those features
361					in whatever way you like.
362
363					=back
364
365					=head1 FUNCTIONAL INTERFACE
366
367					Some documents are copied and modified from L<JSON::XS/FUNCTIONAL INTERFACE>.
368					C<to_json> and C<from_json> are additional functions.
369
370					=head2 encode_json
371
372					$json_text = encode_json $perl_scalar
373
374					Converts the given Perl data structure to a UTF-8 encoded, binary string.
375
376					This function call is functionally identical to:
377
378					$json_text = JSON->new->utf8->encode($perl_scalar)
379
380					=head2 decode_json
381
382					$perl_scalar = decode_json $json_text
383
384					The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
385					to parse that as an UTF-8 encoded JSON text, returning the resulting
386					reference.
387
388					This function call is functionally identical to:
389
390					$perl_scalar = JSON->new->utf8->decode($json_text)
391
392
393					=head2 to_json
394
395					$json_text = to_json($perl_scalar)
396
397					Converts the given Perl data structure to a json string.
398
399					This function call is functionally identical to:
400
401					$json_text = JSON->new->encode($perl_scalar)
402
403					Takes a hash reference as the second.
404
405					$json_text = to_json($perl_scalar, $flag_hashref)
406
407					So,
408
409					$json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1})
410
411					equivalent to:
412
413					$json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
414
415					If you want to write a modern perl code which communicates to outer world,
416					you should use C<encode_json> (supposed that JSON data are encoded in UTF-8).
417
418					=head2 from_json
419
420					$perl_scalar = from_json($json_text)
421
422					The opposite of C<to_json>: expects a json string and tries
423					to parse it, returning the resulting reference.
424
425					This function call is functionally identical to:
426
427					$perl_scalar = JSON->decode($json_text)
428
429					Takes a hash reference as the second.
430
431					$perl_scalar = from_json($json_text, $flag_hashref)
432
433					So,
434
435					$perl_scalar = from_json($json_text, {utf8 => 1})
436
437					equivalent to:
438
439					$perl_scalar = JSON->new->utf8(1)->decode($json_text)
440
441					If you want to write a modern perl code which communicates to outer world,
442					you should use C<decode_json> (supposed that JSON data are encoded in UTF-8).
443
444					=head2 JSON::is_bool
445
446					$is_boolean = JSON::is_bool($scalar)
447
448					Returns true if the passed scalar represents either JSON::true or
449					JSON::false, two constants that act like C<1> and C<0> respectively
450					and are also used to represent JSON C<true> and C<false> in Perl strings.
451
452					=head2 JSON::true
453
454					Returns JSON true value which is blessed object.
455					It C<isa> JSON::Boolean object.
456
457					=head2 JSON::false
458
459					Returns JSON false value which is blessed object.
460					It C<isa> JSON::Boolean object.
461
462					=head2 JSON::null
463
464					Returns C<undef>.
465
466					See L<MAPPING>, below, for more information on how JSON values are mapped to
467					Perl.
468
469					=head1 HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER
470
471					This section supposes that your perl version is 5.8 or later.
472
473					If you know a JSON text from an outer world - a network, a file content, and so on,
474					is encoded in UTF-8, you should use C<decode_json> or C<JSON> module object
475					with C<utf8> enable. And the decoded result will contain UNICODE characters.
476
477					# from network
478					my $json = JSON->new->utf8;
479					my $json_text = CGI->new->param( 'json_data' );
480					my $perl_scalar = $json->decode( $json_text );
481
482					# from file content
483					local $/;
484					open( my $fh, '<', 'json.data' );
485					$json_text = <$fh>;
486					$perl_scalar = decode_json( $json_text );
487
488					If an outer data is not encoded in UTF-8, firstly you should C<decode> it.
489
490					use Encode;
491					local $/;
492					open( my $fh, '<', 'json.data' );
493					my $encoding = 'cp932';
494					my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE
495
496					# or you can write the below code.
497					#
498					# open( my $fh, "<:encoding($encoding)", 'json.data' );
499					# $unicode_json_text = <$fh>;
500
501					In this case, C<$unicode_json_text> is of course UNICODE string.
502					So you B<cannot> use C<decode_json> nor C<JSON> module object with C<utf8> enable.
503					Instead of them, you use C<JSON> module object with C<utf8> disable or C<from_json>.
504
505					$perl_scalar = $json->utf8(0)->decode( $unicode_json_text );
506					# or
507					$perl_scalar = from_json( $unicode_json_text );
508
509					Or C<encode 'utf8'> and C<decode_json>:
510
511					$perl_scalar = decode_json( encode( 'utf8', $unicode_json_text ) );
512					# this way is not efficient.
513
514					And now, you want to convert your C<$perl_scalar> into JSON data and
515					send it to an outer world - a network or a file content, and so on.
516
517					Your data usually contains UNICODE strings and you want the converted data to be encoded
518					in UTF-8, you should use C<encode_json> or C<JSON> module object with C<utf8> enable.
519
520					print encode_json( $perl_scalar ); # to a network? file? or display?
521					# or
522					print $json->utf8->encode( $perl_scalar );
523
524					If C<$perl_scalar> does not contain UNICODE but C<$encoding>-encoded strings
525					for some reason, then its characters are regarded as B<latin1> for perl
526					(because it does not concern with your $encoding).
527					You B<cannot> use C<encode_json> nor C<JSON> module object with C<utf8> enable.
528					Instead of them, you use C<JSON> module object with C<utf8> disable or C<to_json>.
529					Note that the resulted text is a UNICODE string but no problem to print it.
530
531					# $perl_scalar contains $encoding encoded string values
532					$unicode_json_text = $json->utf8(0)->encode( $perl_scalar );
533					# or
534					$unicode_json_text = to_json( $perl_scalar );
535					# $unicode_json_text consists of characters less than 0x100
536					print $unicode_json_text;
537
538					Or C<decode $encoding> all string values and C<encode_json>:
539
540					$perl_scalar->{ foo } = decode( $encoding, $perl_scalar->{ foo } );
541					# ... do it to each string values, then encode_json
542					$json_text = encode_json( $perl_scalar );
543
544					This method is a proper way but probably not efficient.
545
546					See to L<Encode>, L<perluniintro>.
547
548
549					=head1 COMMON OBJECT-ORIENTED INTERFACE
550
551					=head2 new
552
553					$json = JSON->new
554
555					Returns a new C<JSON> object inherited from either JSON::XS or JSON::PP
556					that can be used to de/encode JSON strings.
557
558					All boolean flags described below are by default I<disabled>.
559
560					The mutators for flags all return the JSON object again and thus calls can
561					be chained:
562
563					my $json = JSON->new->utf8->space_after->encode({a => [1,2]})
564					=> {"a": [1, 2]}
565
566					=head2 ascii
567
568					$json = $json->ascii([$enable])
569
570					$enabled = $json->get_ascii
571
572					If $enable is true (or missing), then the encode method will not generate characters outside
573					the code range 0..127. Any Unicode characters outside that range will be escaped using either
574					a single \uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
575
576					If $enable is false, then the encode method will not escape Unicode characters unless
577					required by the JSON syntax or other flags. This results in a faster and more compact format.
578
579					This feature depends on the used Perl version and environment.
580
581					See to L<JSON::PP/UNICODE HANDLING ON PERLS> if the backend is PP.
582
583					JSON->new->ascii(1)->encode([chr 0x10401])
584					=> ["\ud801\udc01"]
585
586					=head2 latin1
587
588					$json = $json->latin1([$enable])
589
590					$enabled = $json->get_latin1
591
592					If $enable is true (or missing), then the encode method will encode the resulting JSON
593					text as latin1 (or iso-8859-1), escaping any characters outside the code range 0..255.
594
595					If $enable is false, then the encode method will not escape Unicode characters
596					unless required by the JSON syntax or other flags.
597
598					JSON->new->latin1->encode (["\x{89}\x{abc}"]
599					=> ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
600
601					=head2 utf8
602
603					$json = $json->utf8([$enable])
604
605					$enabled = $json->get_utf8
606
607					If $enable is true (or missing), then the encode method will encode the JSON result
608					into UTF-8, as required by many protocols, while the decode method expects to be handled
609					an UTF-8-encoded string. Please note that UTF-8-encoded strings do not contain any
610					characters outside the range 0..255, they are thus useful for bytewise/binary I/O.
611
612					In future versions, enabling this option might enable autodetection of the UTF-16 and UTF-32
613					encoding families, as described in RFC4627.
614
615					If $enable is false, then the encode method will return the JSON string as a (non-encoded)
616					Unicode string, while decode expects thus a Unicode string. Any decoding or encoding
617					(e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module.
618
619
620					Example, output UTF-16BE-encoded JSON:
621
622					use Encode;
623					$jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
624
625					Example, decode UTF-32LE-encoded JSON:
626
627					use Encode;
628					$object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
629
630					See to L<JSON::PP/UNICODE HANDLING ON PERLS> if the backend is PP.
631
632
633					=head2 pretty
634
635					$json = $json->pretty([$enable])
636
637					This enables (or disables) all of the C<indent>, C<space_before> and
638					C<space_after> (and in the future possibly more) flags in one call to
639					generate the most readable (or most compact) form possible.
640
641					Equivalent to:
642
643					$json->indent->space_before->space_after
644
645					The indent space length is three and JSON::XS cannot change the indent
646					space length.
647
648					=head2 indent
649
650					$json = $json->indent([$enable])
651
652					$enabled = $json->get_indent
653
654					If C<$enable> is true (or missing), then the C<encode> method will use a multiline
655					format as output, putting every array member or object/hash key-value pair
656					into its own line, identifying them properly.
657
658					If C<$enable> is false, no newlines or indenting will be produced, and the
659					resulting JSON text is guaranteed not to contain any C<newlines>.
660
661					This setting has no effect when decoding JSON texts.
662
663					The indent space length is three.
664					With JSON::PP, you can also access C<indent_length> to change indent space length.
665
666
667					=head2 space_before
668
669					$json = $json->space_before([$enable])
670
671					$enabled = $json->get_space_before
672
673					If C<$enable> is true (or missing), then the C<encode> method will add an extra
674					optional space before the C<:> separating keys from values in JSON objects.
675
676					If C<$enable> is false, then the C<encode> method will not add any extra
677					space at those places.
678
679					This setting has no effect when decoding JSON texts.
680
681					Example, space_before enabled, space_after and indent disabled:
682
683					{"key" :"value"}
684
685
686					=head2 space_after
687
688					$json = $json->space_after([$enable])
689
690					$enabled = $json->get_space_after
691
692					If C<$enable> is true (or missing), then the C<encode> method will add an extra
693					optional space after the C<:> separating keys from values in JSON objects
694					and extra whitespace after the C<,> separating key-value pairs and array
695					members.
696
697					If C<$enable> is false, then the C<encode> method will not add any extra
698					space at those places.
699
700					This setting has no effect when decoding JSON texts.
701
702					Example, space_before and indent disabled, space_after enabled:
703
704					{"key": "value"}
705
706
707					=head2 relaxed
708
709					$json = $json->relaxed([$enable])
710
711					$enabled = $json->get_relaxed
712
713					If C<$enable> is true (or missing), then C<decode> will accept some
714					extensions to normal JSON syntax (see below). C<encode> will not be
715					affected in anyway. I<Be aware that this option makes you accept invalid
716					JSON texts as if they were valid!>. I suggest only to use this option to
717					parse application-specific files written by humans (configuration files,
718					resource files etc.)
719
720					If C<$enable> is false (the default), then C<decode> will only accept
721					valid JSON texts.
722
723					Currently accepted extensions are:
724
725					=over 4
726
727					=item * list items can have an end-comma
728
729					JSON I<separates> array elements and key-value pairs with commas. This
730					can be annoying if you write JSON texts manually and want to be able to
731					quickly append elements, so this extension accepts comma at the end of
732					such items not just between them:
733
734					[
735					1,
736					2, <- this comma not normally allowed
737					]
738					{
739					"k1": "v1",
740					"k2": "v2", <- this comma not normally allowed
741					}
742
743					=item * shell-style '#'-comments
744
745					Whenever JSON allows whitespace, shell-style comments are additionally
746					allowed. They are terminated by the first carriage-return or line-feed
747					character, after which more white-space and comments are allowed.
748
749					[
750					1, # this comment not allowed in JSON
751					# neither this one...
752					]
753
754					=back
755
756
757					=head2 canonical
758
759					$json = $json->canonical([$enable])
760
761					$enabled = $json->get_canonical
762
763					If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
764					by sorting their keys. This is adding a comparatively high overhead.
765
766					If C<$enable> is false, then the C<encode> method will output key-value
767					pairs in the order Perl stores them (which will likely change between runs
768					of the same script).
769
770					This option is useful if you want the same data structure to be encoded as
771					the same JSON text (given the same overall settings). If it is disabled,
772					the same hash might be encoded differently even if contains the same data,
773					as key-value pairs have no inherent ordering in Perl.
774
775					This setting has no effect when decoding JSON texts.
776
777					=head2 allow_nonref
778
779					$json = $json->allow_nonref([$enable])
780
781					$enabled = $json->get_allow_nonref
782
783					If C<$enable> is true (or missing), then the C<encode> method can convert a
784					non-reference into its corresponding string, number or null JSON value,
785					which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
786					values instead of croaking.
787
788					If C<$enable> is false, then the C<encode> method will croak if it isn't
789					passed an arrayref or hashref, as JSON texts must either be an object
790					or array. Likewise, C<decode> will croak if given something that is not a
791					JSON object or array.
792
793					JSON->new->allow_nonref->encode ("Hello, World!")
794					=> "Hello, World!"
795
796					=head2 allow_unknown
797
798					$json = $json->allow_unknown ([$enable])
799
800					$enabled = $json->get_allow_unknown
801
802					If $enable is true (or missing), then "encode" will not throw an
803					exception when it encounters values it cannot represent in JSON (for
804					example, filehandles) but instead will encode a JSON "null" value.
805					Note that blessed objects are not included here and are handled
806					separately by c<allow_nonref>.
807
808					If $enable is false (the default), then "encode" will throw an
809					exception when it encounters anything it cannot encode as JSON.
810
811					This option does not affect "decode" in any way, and it is
812					recommended to leave it off unless you know your communications
813					partner.
814
815					=head2 allow_blessed
816
817					$json = $json->allow_blessed([$enable])
818
819					$enabled = $json->get_allow_blessed
820
821					If C<$enable> is true (or missing), then the C<encode> method will not
822					barf when it encounters a blessed reference. Instead, the value of the
823					B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
824					disabled or no C<TO_JSON> method found) or a representation of the
825					object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
826					encoded. Has no effect on C<decode>.
827
828					If C<$enable> is false (the default), then C<encode> will throw an
829					exception when it encounters a blessed object.
830
831
832					=head2 convert_blessed
833
834					$json = $json->convert_blessed([$enable])
835
836					$enabled = $json->get_convert_blessed
837
838					If C<$enable> is true (or missing), then C<encode>, upon encountering a
839					blessed object, will check for the availability of the C<TO_JSON> method
840					on the object's class. If found, it will be called in scalar context
841					and the resulting scalar will be encoded instead of the object. If no
842					C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
843					to do.
844
845					The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
846					returns other blessed objects, those will be handled in the same
847					way. C<TO_JSON> must take care of not causing an endless recursion cycle
848					(== crash) in this case. The name of C<TO_JSON> was chosen because other
849					methods called by the Perl core (== not by the user of the object) are
850					usually in upper case letters and to avoid collisions with the C<to_json>
851					function or method.
852
853					This setting does not yet influence C<decode> in any way.
854
855					If C<$enable> is false, then the C<allow_blessed> setting will decide what
856					to do when a blessed object is found.
857
858					=over
859
860					=item convert_blessed_universally mode
861
862					If use C<JSON> with C<-convert_blessed_universally>, the C<UNIVERSAL::TO_JSON>
863					subroutine is defined as the below code:
864
865					*UNIVERSAL::TO_JSON = sub {
866					my $b_obj = B::svref_2object( $_[0] );
867					return $b_obj->isa('B::HV') ? { %{ $_[0] } }
868					: $b_obj->isa('B::AV') ? [ @{ $_[0] } ]
869					: undef
870					;
871					}
872
873					This will cause that C<encode> method converts simple blessed objects into
874					JSON objects as non-blessed object.
875
876					JSON -convert_blessed_universally;
877					$json->allow_blessed->convert_blessed->encode( $blessed_object )
878
879					This feature is experimental and may be removed in the future.
880
881					=back
882
883					=head2 filter_json_object
884
885					$json = $json->filter_json_object([$coderef])
886
887					When C<$coderef> is specified, it will be called from C<decode> each
888					time it decodes a JSON object. The only argument passed to the coderef
889					is a reference to the newly-created hash. If the code references returns
890					a single scalar (which need not be a reference), this value
891					(i.e. a copy of that scalar to avoid aliasing) is inserted into the
892					deserialised data structure. If it returns an empty list
893					(NOTE: I<not> C<undef>, which is a valid scalar), the original deserialised
894					hash will be inserted. This setting can slow down decoding considerably.
895
896					When C<$coderef> is omitted or undefined, any existing callback will
897					be removed and C<decode> will not change the deserialised hash in any
898					way.
899
900					Example, convert all JSON objects into the integer 5:
901
902					my $js = JSON->new->filter_json_object (sub { 5 });
903					# returns [5]
904					$js->decode ('[{}]'); # the given subroutine takes a hash reference.
905					# throw an exception because allow_nonref is not enabled
906					# so a lone 5 is not allowed.
907					$js->decode ('{"a":1, "b":2}');
908
909
910					=head2 filter_json_single_key_object
911
912					$json = $json->filter_json_single_key_object($key [=> $coderef])
913
914					Works remotely similar to C<filter_json_object>, but is only called for
915					JSON objects having a single key named C<$key>.
916
917					This C<$coderef> is called before the one specified via
918					C<filter_json_object>, if any. It gets passed the single value in the JSON
919					object. If it returns a single value, it will be inserted into the data
920					structure. If it returns nothing (not even C<undef> but the empty list),
921					the callback from C<filter_json_object> will be called next, as if no
922					single-key callback were specified.
923
924					If C<$coderef> is omitted or undefined, the corresponding callback will be
925					disabled. There can only ever be one callback for a given key.
926
927					As this callback gets called less often then the C<filter_json_object>
928					one, decoding speed will not usually suffer as much. Therefore, single-key
929					objects make excellent targets to serialise Perl objects into, especially
930					as single-key JSON objects are as close to the type-tagged value concept
931					as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
932					support this in any way, so you need to make sure your data never looks
933					like a serialised Perl hash.
934
935					Typical names for the single object key are C<__class_whatever__>, or
936					C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
937					things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
938					with real hashes.
939
940					Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
941					into the corresponding C<< $WIDGET{<id>} >> object:
942
943					# return whatever is in $WIDGET{5}:
944					JSON
945					->new
946					->filter_json_single_key_object (__widget__ => sub {
947					$WIDGET{ $_[0] }
948					})
949					->decode ('{"__widget__": 5')
950
951					# this can be used with a TO_JSON method in some "widget" class
952					# for serialisation to json:
953					sub WidgetBase::TO_JSON {
954					my ($self) = @_;
955
956					unless ($self->{id}) {
957					$self->{id} = ..get..some..id..;
958					$WIDGET{$self->{id}} = $self;
959					}
960
961					{ __widget__ => $self->{id} }
962					}
963
964
965					=head2 shrink
966
967					$json = $json->shrink([$enable])
968
969					$enabled = $json->get_shrink
970
971					With JSON::XS, this flag resizes strings generated by either
972					C<encode> or C<decode> to their minimum size possible. This can save
973					memory when your JSON texts are either very very long or you have many
974					short strings. It will also try to downgrade any strings to octet-form
975					if possible: perl stores strings internally either in an encoding called
976					UTF-X or in octet-form. The latter cannot store everything but uses less
977					space in general (and some buggy Perl or C code might even rely on that
978					internal representation being used).
979
980					With JSON::PP, it is noop about resizing strings but tries
981					C<utf8::downgrade> to the returned string by C<encode>. See to L<utf8>.
982
983					See to L<JSON::XS/OBJECT-ORIENTED INTERFACE> and L<JSON::PP/METHODS>.
984
985					=head2 max_depth
986
987					$json = $json->max_depth([$maximum_nesting_depth])
988
989					$max_depth = $json->get_max_depth
990
991					Sets the maximum nesting level (default C<512>) accepted while encoding
992					or decoding. If a higher nesting level is detected in JSON text or a Perl
993					data structure, then the encoder and decoder will stop and croak at that
994					point.
995
996					Nesting level is defined by number of hash- or arrayrefs that the encoder
997					needs to traverse to reach a given point or the number of C<{> or C<[>
998					characters without their matching closing parenthesis crossed to reach a
999					given character in a string.
1000
1001					If no argument is given, the highest possible setting will be used, which
1002					is rarely useful.
1003
1004					Note that nesting is implemented by recursion in C. The default value has
1005					been chosen to be as large as typical operating systems allow without
1006					crashing. (JSON::XS)
1007
1008					With JSON::PP as the backend, when a large value (100 or more) was set and
1009					it de/encodes a deep nested object/text, it may raise a warning
1010					'Deep recursion on subroutine' at the perl runtime phase.
1011
1012					See L<JSON::XS/SECURITY CONSIDERATIONS> for more info on why this is useful.
1013
1014					=head2 max_size
1015
1016					$json = $json->max_size([$maximum_string_size])
1017
1018					$max_size = $json->get_max_size
1019
1020					Set the maximum length a JSON text may have (in bytes) where decoding is
1021					being attempted. The default is C<0>, meaning no limit. When C<decode>
1022					is called on a string that is longer then this many bytes, it will not
1023					attempt to decode the string but throw an exception. This setting has no
1024					effect on C<encode> (yet).
1025
1026					If no argument is given, the limit check will be deactivated (same as when
1027					C<0> is specified).
1028
1029					See L<JSON::XS/SECURITY CONSIDERATIONS>, below, for more info on why this is useful.
1030
1031					=head2 encode
1032
1033					$json_text = $json->encode($perl_scalar)
1034
1035					Converts the given Perl data structure (a simple scalar or a reference
1036					to a hash or array) to its JSON representation. Simple scalars will be
1037					converted into JSON string or number sequences, while references to arrays
1038					become JSON arrays and references to hashes become JSON objects. Undefined
1039					Perl values (e.g. C<undef>) become JSON C<null> values.
1040					References to the integers C<0> and C<1> are converted into C<true> and C<false>.
1041
1042					=head2 decode
1043
1044					$perl_scalar = $json->decode($json_text)
1045
1046					The opposite of C<encode>: expects a JSON text and tries to parse it,
1047					returning the resulting simple scalar or reference. Croaks on error.
1048
1049					JSON numbers and strings become simple Perl scalars. JSON arrays become
1050					Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
1051					C<1> (C<JSON::true>), C<false> becomes C<0> (C<JSON::false>) and
1052					C<null> becomes C<undef>.
1053
1054					=head2 decode_prefix
1055
1056					($perl_scalar, $characters) = $json->decode_prefix($json_text)
1057
1058					This works like the C<decode> method, but instead of raising an exception
1059					when there is trailing garbage after the first JSON object, it will
1060					silently stop parsing there and return the number of characters consumed
1061					so far.
1062
1063					JSON->new->decode_prefix ("[1] the tail")
1064					=> ([], 3)
1065
1066					See to L<JSON::XS/OBJECT-ORIENTED INTERFACE>
1067
1068					=head2 property
1069
1070					$boolean = $json->property($property_name)
1071
1072					Returns a boolean value about above some properties.
1073
1074					The available properties are C<ascii>, C<latin1>, C<utf8>,
1075					C<indent>,C<space_before>, C<space_after>, C<relaxed>, C<canonical>,
1076					C<allow_nonref>, C<allow_unknown>, C<allow_blessed>, C<convert_blessed>,
1077					C<shrink>, C<max_depth> and C<max_size>.
1078
1079					$boolean = $json->property('utf8');
1080					=> 0
1081					$json->utf8;
1082					$boolean = $json->property('utf8');
1083					=> 1
1084
1085					Sets the property with a given boolean value.
1086
1087					$json = $json->property($property_name => $boolean);
1088
1089					With no argument, it returns all the above properties as a hash reference.
1090
1091					$flag_hashref = $json->property();
1092
1093					=head1 INCREMENTAL PARSING
1094
1095					Most of this section are copied and modified from L<JSON::XS/INCREMENTAL PARSING>.
1096
1097					In some cases, there is the need for incremental parsing of JSON texts.
1098					This module does allow you to parse a JSON stream incrementally.
1099					It does so by accumulating text until it has a full JSON object, which
1100					it then can decode. This process is similar to using C<decode_prefix>
1101					to see if a full JSON object is available, but is much more efficient
1102					(and can be implemented with a minimum of method calls).
1103
1104					The backend module will only attempt to parse the JSON text once it is sure it
1105					has enough text to get a decisive result, using a very simple but
1106					truly incremental parser. This means that it sometimes won't stop as
1107					early as the full parser, for example, it doesn't detect parenthesis
1108					mismatches. The only thing it guarantees is that it starts decoding as
1109					soon as a syntactically valid JSON text has been seen. This means you need
1110					to set resource limits (e.g. C<max_size>) to ensure the parser will stop
1111					parsing in the presence if syntax errors.
1112
1113					The following methods implement this incremental parser.
1114
1115					=head2 incr_parse
1116
1117					$json->incr_parse( [$string] ) # void context
1118
1119					$obj_or_undef = $json->incr_parse( [$string] ) # scalar context
1120
1121					@obj_or_empty = $json->incr_parse( [$string] ) # list context
1122
1123					This is the central parsing function. It can both append new text and
1124					extract objects from the stream accumulated so far (both of these
1125					functions are optional).
1126
1127					If C<$string> is given, then this string is appended to the already
1128					existing JSON fragment stored in the C<$json> object.
1129
1130					After that, if the function is called in void context, it will simply
1131					return without doing anything further. This can be used to add more text
1132					in as many chunks as you want.
1133
1134					If the method is called in scalar context, then it will try to extract
1135					exactly I<one> JSON object. If that is successful, it will return this
1136					object, otherwise it will return C<undef>. If there is a parse error,
1137					this method will croak just as C<decode> would do (one can then use
1138					C<incr_skip> to skip the erroneous part). This is the most common way of
1139					using the method.
1140
1141					And finally, in list context, it will try to extract as many objects
1142					from the stream as it can find and return them, or the empty list
1143					otherwise. For this to work, there must be no separators between the JSON
1144					objects or arrays, instead they must be concatenated back-to-back. If
1145					an error occurs, an exception will be raised as in the scalar context
1146					case. Note that in this case, any previously-parsed JSON texts will be
1147					lost.
1148
1149					Example: Parse some JSON arrays/objects in a given string and return them.
1150
1151					my @objs = JSON->new->incr_parse ("[5][7][1,2]");
1152
1153					=head2 incr_text
1154
1155					$lvalue_string = $json->incr_text
1156
1157					This method returns the currently stored JSON fragment as an lvalue, that
1158					is, you can manipulate it. This I<only> works when a preceding call to
1159					C<incr_parse> in I<scalar context> successfully returned an object. Under
1160					all other circumstances you must not call this function (I mean it.
1161					although in simple tests it might actually work, it I<will> fail under
1162					real world conditions). As a special exception, you can also call this
1163					method before having parsed anything.
1164
1165					This function is useful in two cases: a) finding the trailing text after a
1166					JSON object or b) parsing multiple JSON objects separated by non-JSON text
1167					(such as commas).
1168
1169					$json->incr_text =~ s/\s,\s//;
1170
1171					In Perl 5.005, C<lvalue> attribute is not available.
1172					You must write codes like the below:
1173
1174					$string = $json->incr_text;
1175					$string =~ s/\s,\s//;
1176					$json->incr_text( $string );
1177
1178					=head2 incr_skip
1179
1180					$json->incr_skip
1181
1182					This will reset the state of the incremental parser and will remove the
1183					parsed text from the input buffer. This is useful after C<incr_parse>
1184					died, in which case the input buffer and incremental parser state is left
1185					unchanged, to skip the text parsed so far and to reset the parse state.
1186
1187					=head2 incr_reset
1188
1189					$json->incr_reset
1190
1191					This completely resets the incremental parser, that is, after this call,
1192					it will be as if the parser had never parsed anything.
1193
1194					This is useful if you want to repeatedly parse JSON objects and want to
1195					ignore any trailing data, which means you have to reset the parser after
1196					each successful decode.
1197
1198					See to L<JSON::XS/INCREMENTAL PARSING> for examples.
1199
1200
1201					=head1 JSON::PP SUPPORT METHODS
1202
1203					The below methods are JSON::PP own methods, so when C<JSON> works
1204					with JSON::PP (i.e. the created object is a JSON::PP object), available.
1205					See to L<JSON::PP/JSON::PP OWN METHODS> in detail.
1206
1207					If you use C<JSON> with additional C<-support_by_pp>, some methods
1208					are available even with JSON::XS. See to L<USE PP FEATURES EVEN THOUGH XS BACKEND>.
1209
1210					BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' }
1211
1212					use JSON -support_by_pp;
1213
1214					my $json = JSON->new;
1215					$json->allow_nonref->escape_slash->encode("/");
1216
1217					# functional interfaces too.
1218					print to_json(["/"], {escape_slash => 1});
1219					print from_json('["foo"]', {utf8 => 1});
1220
1221					If you do not want to all functions but C<-support_by_pp>,
1222					use C<-no_export>.
1223
1224					use JSON -support_by_pp, -no_export;
1225					# functional interfaces are not exported.
1226
1227					=head2 allow_singlequote
1228
1229					$json = $json->allow_singlequote([$enable])
1230
1231					If C<$enable> is true (or missing), then C<decode> will accept
1232					any JSON strings quoted by single quotations that are invalid JSON
1233					format.
1234
1235					$json->allow_singlequote->decode({"foo":'bar'});
1236					$json->allow_singlequote->decode({'foo':"bar"});
1237					$json->allow_singlequote->decode({'foo':'bar'});
1238
1239					As same as the C<relaxed> option, this option may be used to parse
1240					application-specific files written by humans.
1241
1242					=head2 allow_barekey
1243
1244					$json = $json->allow_barekey([$enable])
1245
1246					If C<$enable> is true (or missing), then C<decode> will accept
1247					bare keys of JSON object that are invalid JSON format.
1248
1249					As same as the C<relaxed> option, this option may be used to parse
1250					application-specific files written by humans.
1251
1252					$json->allow_barekey->decode('{foo:"bar"}');
1253
1254					=head2 allow_bignum
1255
1256					$json = $json->allow_bignum([$enable])
1257
1258					If C<$enable> is true (or missing), then C<decode> will convert
1259					the big integer Perl cannot handle as integer into a L<Math::BigInt>
1260					object and convert a floating number (any) into a L<Math::BigFloat>.
1261
1262					On the contrary, C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat>
1263					objects into JSON numbers with C<allow_blessed> enable.
1264
1265					$json->allow_nonref->allow_blessed->allow_bignum;
1266					$bigfloat = $json->decode('2.000000000000000000000000001');
1267					print $json->encode($bigfloat);
1268					# => 2.000000000000000000000000001
1269
1270					See to L<MAPPING> about the conversion of JSON number.
1271
1272					=head2 loose
1273
1274					$json = $json->loose([$enable])
1275
1276					The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON strings
1277					and the module doesn't allow to C<decode> to these (except for \x2f).
1278					If C<$enable> is true (or missing), then C<decode> will accept these
1279					unescaped strings.
1280
1281					$json->loose->decode(qq\|["abc
1282					def"]\|);
1283
1284					See to L<JSON::PP/JSON::PP OWN METHODS>.
1285
1286					=head2 escape_slash
1287
1288					$json = $json->escape_slash([$enable])
1289
1290					According to JSON Grammar, I<slash> (U+002F) is escaped. But by default
1291					JSON backend modules encode strings without escaping slash.
1292
1293					If C<$enable> is true (or missing), then C<encode> will escape slashes.
1294
1295					=head2 indent_length
1296
1297					$json = $json->indent_length($length)
1298
1299					With JSON::XS, The indent space length is 3 and cannot be changed.
1300					With JSON::PP, it sets the indent space length with the given $length.
1301					The default is 3. The acceptable range is 0 to 15.
1302
1303					=head2 sort_by
1304
1305					$json = $json->sort_by($function_name)
1306					$json = $json->sort_by($subroutine_ref)
1307
1308					If $function_name or $subroutine_ref are set, its sort routine are used.
1309
1310					$js = $pc->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })->encode($obj);
1311					# is($js, q\|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}\|);
1312
1313					$js = $pc->sort_by('own_sort')->encode($obj);
1314					# is($js, q\|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}\|);
1315
1316					sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b }
1317
1318					As the sorting routine runs in the JSON::PP scope, the given
1319					subroutine name and the special variables C<$a>, C<$b> will begin
1320					with 'JSON::PP::'.
1321
1322					If $integer is set, then the effect is same as C<canonical> on.
1323
1324					See to L<JSON::PP/JSON::PP OWN METHODS>.
1325
1326					=head1 MAPPING
1327
1328					This section is copied from JSON::XS and modified to C<JSON>.
1329					JSON::XS and JSON::PP mapping mechanisms are almost equivalent.
1330
1331					See to L<JSON::XS/MAPPING>.
1332
1333					=head2 JSON -> PERL
1334
1335					=over 4
1336
1337					=item object
1338
1339					A JSON object becomes a reference to a hash in Perl. No ordering of object
1340					keys is preserved (JSON does not preserver object key ordering itself).
1341
1342					=item array
1343
1344					A JSON array becomes a reference to an array in Perl.
1345
1346					=item string
1347
1348					A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
1349					are represented by the same codepoints in the Perl string, so no manual
1350					decoding is necessary.
1351
1352					=item number
1353
1354					A JSON number becomes either an integer, numeric (floating point) or
1355					string scalar in perl, depending on its range and any fractional parts. On
1356					the Perl level, there is no difference between those as Perl handles all
1357					the conversion details, but an integer may take slightly less memory and
1358					might represent more values exactly than floating point numbers.
1359
1360					If the number consists of digits only, C<JSON> will try to represent
1361					it as an integer value. If that fails, it will try to represent it as
1362					a numeric (floating point) value if that is possible without loss of
1363					precision. Otherwise it will preserve the number as a string value (in
1364					which case you lose roundtripping ability, as the JSON number will be
1365					re-encoded to a JSON string).
1366
1367					Numbers containing a fractional or exponential part will always be
1368					represented as numeric (floating point) values, possibly at a loss of
1369					precision (in which case you might lose perfect roundtripping ability, but
1370					the JSON number will still be re-encoded as a JSON number).
1371
1372					Note that precision is not accuracy - binary floating point values cannot
1373					represent most decimal fractions exactly, and when converting from and to
1374					floating point, C<JSON> only guarantees precision up to but not including
1375					the least significant bit.
1376
1377					If the backend is JSON::PP and C<allow_bignum> is enable, the big integers
1378					and the numeric can be optionally converted into L<Math::BigInt> and
1379					L<Math::BigFloat> objects.
1380
1381					=item true, false
1382
1383					These JSON atoms become C<JSON::true> and C<JSON::false>,
1384					respectively. They are overloaded to act almost exactly like the numbers
1385					C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
1386					the C<JSON::is_bool> function.
1387
1388					If C<JSON::true> and C<JSON::false> are used as strings or compared as strings,
1389					they represent as C<true> and C<false> respectively.
1390
1391					print JSON::true . "\n";
1392					=> true
1393					print JSON::true + 1;
1394					=> 1
1395
1396					ok(JSON::true eq 'true');
1397					ok(JSON::true eq '1');
1398					ok(JSON::true == 1);
1399
1400					C<JSON> will install these missing overloading features to the backend modules.
1401
1402
1403					=item null
1404
1405					A JSON null atom becomes C<undef> in Perl.
1406
1407					C<JSON::null> returns C<undef>.
1408
1409					=back
1410
1411
1412					=head2 PERL -> JSON
1413
1414					The mapping from Perl to JSON is slightly more difficult, as Perl is a
1415					truly typeless language, so we can only guess which JSON type is meant by
1416					a Perl value.
1417
1418					=over 4
1419
1420					=item hash references
1421
1422					Perl hash references become JSON objects. As there is no inherent ordering
1423					in hash keys (or JSON objects), they will usually be encoded in a
1424					pseudo-random order that can change between runs of the same program but
1425					stays generally the same within a single run of a program. C<JSON>
1426					optionally sort the hash keys (determined by the I<canonical> flag), so
1427					the same data structure will serialise to the same JSON text (given same
1428					settings and version of JSON::XS), but this incurs a runtime overhead
1429					and is only rarely useful, e.g. when you want to compare some JSON text
1430					against another for equality.
1431
1432					In future, the ordered object feature will be added to JSON::PP using C<tie> mechanism.
1433
1434
1435					=item array references
1436
1437					Perl array references become JSON arrays.
1438
1439					=item other references
1440
1441					Other unblessed references are generally not allowed and will cause an
1442					exception to be thrown, except for references to the integers C<0> and
1443					C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1444					also use C<JSON::false> and C<JSON::true> to improve readability.
1445
1446					to_json [\0,JSON::true] # yields [false,true]
1447
1448					=item JSON::true, JSON::false, JSON::null
1449
1450					These special values become JSON true and JSON false values,
1451					respectively. You can also use C<\1> and C<\0> directly if you want.
1452
1453					JSON::null returns C<undef>.
1454
1455					=item blessed objects
1456
1457					Blessed objects are not directly representable in JSON. See the
1458					C<allow_blessed> and C<convert_blessed> methods on various options on
1459					how to deal with this: basically, you can choose between throwing an
1460					exception, encoding the reference as if it weren't blessed, or provide
1461					your own serialiser method.
1462
1463					With C<convert_blessed_universally> mode, C<encode> converts blessed
1464					hash references or blessed array references (contains other blessed references)
1465					into JSON members and arrays.
1466
1467					use JSON -convert_blessed_universally;
1468					JSON->new->allow_blessed->convert_blessed->encode( $blessed_object );
1469
1470					See to L<convert_blessed>.
1471
1472					=item simple scalars
1473
1474					Simple Perl scalars (any scalar that is not a reference) are the most
1475					difficult objects to encode: JSON::XS and JSON::PP will encode undefined scalars as
1476					JSON C<null> values, scalars that have last been used in a string context
1477					before encoding as JSON strings, and anything else as number value:
1478
1479					# dump as number
1480					encode_json [2] # yields [2]
1481					encode_json [-3.0e17] # yields [-3e+17]
1482					my $value = 5; encode_json [$value] # yields [5]
1483
1484					# used as string, so dump as string
1485					print $value;
1486					encode_json [$value] # yields ["5"]
1487
1488					# undef becomes null
1489					encode_json [undef] # yields [null]
1490
1491					You can force the type to be a string by stringifying it:
1492
1493					my $x = 3.1; # some variable containing a number
1494					"$x"; # stringified
1495					$x .= ""; # another, more awkward way to stringify
1496					print $x; # perl does it for you, too, quite often
1497
1498					You can force the type to be a number by numifying it:
1499
1500					my $x = "3"; # some variable containing a string
1501					$x += 0; # numify it, ensuring it will be dumped as a number
1502					$x *= 1; # same thing, the choice is yours.
1503
1504					You can not currently force the type in other, less obscure, ways.
1505
1506					Note that numerical precision has the same meaning as under Perl (so
1507					binary to decimal conversion follows the same rules as in Perl, which
1508					can differ to other languages). Also, your perl interpreter might expose
1509					extensions to the floating point numbers of your platform, such as
1510					infinities or NaN's - these cannot be represented in JSON, and it is an
1511					error to pass those in.
1512
1513					=item Big Number
1514
1515					If the backend is JSON::PP and C<allow_bignum> is enable,
1516					C<encode> converts C<Math::BigInt> objects and C<Math::BigFloat>
1517					objects into JSON numbers.
1518
1519
1520					=back
1521
1522					=head1 JSON and ECMAscript
1523
1524					See to L<JSON::XS/JSON and ECMAscript>.
1525
1526					=head1 JSON and YAML
1527
1528					JSON is not a subset of YAML.
1529					See to L<JSON::XS/JSON and YAML>.
1530
1531
1532					=head1 BACKEND MODULE DECISION
1533
1534					When you use C<JSON>, C<JSON> tries to C<use> JSON::XS. If this call failed, it will
1535					C<uses> JSON::PP. The required JSON::XS version is I<2.2> or later.
1536
1537					The C<JSON> constructor method returns an object inherited from the backend module,
1538					and JSON::XS object is a blessed scalar reference while JSON::PP is a blessed hash
1539					reference.
1540
1541					So, your program should not depend on the backend module, especially
1542					returned objects should not be modified.
1543
1544					my $json = JSON->new; # XS or PP?
1545					$json->{stash} = 'this is xs object'; # this code may raise an error!
1546
1547					To check the backend module, there are some methods - C<backend>, C<is_pp> and C<is_xs>.
1548
1549					JSON->backend; # 'JSON::XS' or 'JSON::PP'
1550
1551					JSON->backend->is_pp: # 0 or 1
1552
1553					JSON->backend->is_xs: # 1 or 0
1554
1555					$json->is_xs; # 1 or 0
1556
1557					$json->is_pp; # 0 or 1
1558
1559
1560					If you set an environment variable C<PERL_JSON_BACKEND>, the calling action will be changed.
1561
1562					=over
1563
1564					=item PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP'
1565
1566					Always use JSON::PP
1567
1568					=item PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP'
1569
1570					(The default) Use compiled JSON::XS if it is properly compiled & installed,
1571					otherwise use JSON::PP.
1572
1573					=item PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS'
1574
1575					Always use compiled JSON::XS, die if it isn't properly compiled & installed.
1576
1577					=item PERL_JSON_BACKEND = 'JSON::backportPP'
1578
1579					Always use JSON::backportPP.
1580					JSON::backportPP is JSON::PP back port module.
1581					C<JSON> includes JSON::backportPP instead of JSON::PP.
1582
1583					=back
1584
1585					These ideas come from L<DBI::PurePerl> mechanism.
1586
1587					example:
1588
1589					BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' }
1590					use JSON; # always uses JSON::PP
1591
1592					In future, it may be able to specify another module.
1593
1594					=head1 USE PP FEATURES EVEN THOUGH XS BACKEND
1595
1596					Many methods are available with either JSON::XS or JSON::PP and
1597					when the backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS unsupported)
1598					method is called, it will C<warn> and be noop.
1599
1600					But If you C<use> C<JSON> passing the optional string C<-support_by_pp>,
1601					it makes a part of those unsupported methods available.
1602					This feature is achieved by using JSON::PP in C<de/encode>.
1603
1604					BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS
1605					use JSON -support_by_pp;
1606					my $json = JSON->new;
1607					$json->allow_nonref->escape_slash->encode("/");
1608
1609					At this time, the returned object is a C<JSON::Backend::XS::Supportable>
1610					object (re-blessed XS object), and by checking JSON::XS unsupported flags
1611					in de/encoding, can support some unsupported methods - C<loose>, C<allow_bignum>,
1612					C<allow_barekey>, C<allow_singlequote>, C<escape_slash> and C<indent_length>.
1613
1614					When any unsupported methods are not enable, C<XS de/encode> will be
1615					used as is. The switch is achieved by changing the symbolic tables.
1616
1617					C<-support_by_pp> is effective only when the backend module is JSON::XS
1618					and it makes the de/encoding speed down a bit.
1619
1620					See to L<JSON::PP SUPPORT METHODS>.
1621
1622					=head1 INCOMPATIBLE CHANGES TO OLD VERSION
1623
1624					There are big incompatibility between new version (2.00) and old (1.xx).
1625					If you use old C<JSON> 1.xx in your code, please check it.
1626
1627					See to L<Transition ways from 1.xx to 2.xx.>
1628
1629					=over
1630
1631					=item jsonToObj and objToJson are obsoleted.
1632
1633					Non Perl-style name C<jsonToObj> and C<objToJson> are obsoleted
1634					(but not yet deleted from the source).
1635					If you use these functions in your code, please replace them
1636					with C<from_json> and C<to_json>.
1637
1638
1639					=item Global variables are no longer available.
1640
1641					C<JSON> class variables - C<$JSON::AUTOCONVERT>, C<$JSON::BareKey>, etc...
1642					- are not available any longer.
1643					Instead, various features can be used through object methods.
1644
1645
1646					=item Package JSON::Converter and JSON::Parser are deleted.
1647
1648					Now C<JSON> bundles with JSON::PP which can handle JSON more properly than them.
1649
1650					=item Package JSON::NotString is deleted.
1651
1652					There was C<JSON::NotString> class which represents JSON value C<true>, C<false>, C<null>
1653					and numbers. It was deleted and replaced by C<JSON::Boolean>.
1654
1655					C<JSON::Boolean> represents C<true> and C<false>.
1656
1657					C<JSON::Boolean> does not represent C<null>.
1658
1659					C<JSON::null> returns C<undef>.
1660
1661					C<JSON> makes L<JSON::XS::Boolean> and L<JSON::PP::Boolean> is-a relation
1662					to L<JSON::Boolean>.
1663
1664					=item function JSON::Number is obsoleted.
1665
1666					C<JSON::Number> is now needless because JSON::XS and JSON::PP have
1667					round-trip integrity.
1668
1669					=item JSONRPC modules are deleted.
1670
1671					Perl implementation of JSON-RPC protocol - C<JSONRPC >, C<JSONRPC::Transport::HTTP>
1672					and C<Apache::JSONRPC > are deleted in this distribution.
1673					Instead of them, there is L<JSON::RPC> which supports JSON-RPC protocol version 1.1.
1674
1675					=back
1676
1677					=head2 Transition ways from 1.xx to 2.xx.
1678
1679					You should set C<suport_by_pp> mode firstly, because
1680					it is always successful for the below codes even with JSON::XS.
1681
1682					use JSON -support_by_pp;
1683
1684					=over
1685
1686					=item Exported jsonToObj (simple)
1687
1688					from_json($json_text);
1689
1690					=item Exported objToJson (simple)
1691
1692					to_json($perl_scalar);
1693
1694					=item Exported jsonToObj (advanced)
1695
1696					$flags = {allow_barekey => 1, allow_singlequote => 1};
1697					from_json($json_text, $flags);
1698
1699					equivalent to:
1700
1701					$JSON::BareKey = 1;
1702					$JSON::QuotApos = 1;
1703					jsonToObj($json_text);
1704
1705					=item Exported objToJson (advanced)
1706
1707					$flags = {allow_blessed => 1, allow_barekey => 1};
1708					to_json($perl_scalar, $flags);
1709
1710					equivalent to:
1711
1712					$JSON::BareKey = 1;
1713					objToJson($perl_scalar);
1714
1715					=item jsonToObj as object method
1716
1717					$json->decode($json_text);
1718
1719					=item objToJson as object method
1720
1721					$json->encode($perl_scalar);
1722
1723					=item new method with parameters
1724
1725					The C<new> method in 2.x takes any parameters no longer.
1726					You can set parameters instead;
1727
1728					$json = JSON->new->pretty;
1729
1730					=item $JSON::Pretty, $JSON::Indent, $JSON::Delimiter
1731
1732					If C<indent> is enable, that means C<$JSON::Pretty> flag set. And
1733					C<$JSON::Delimiter> was substituted by C<space_before> and C<space_after>.
1734					In conclusion:
1735
1736					$json->indent->space_before->space_after;
1737
1738					Equivalent to:
1739
1740					$json->pretty;
1741
1742					To change indent length, use C<indent_length>.
1743
1744					(Only with JSON::PP, if C<-support_by_pp> is not used.)
1745
1746					$json->pretty->indent_length(2)->encode($perl_scalar);
1747
1748					=item $JSON::BareKey
1749
1750					(Only with JSON::PP, if C<-support_by_pp> is not used.)
1751
1752					$json->allow_barekey->decode($json_text)
1753
1754					=item $JSON::ConvBlessed
1755
1756					use C<-convert_blessed_universally>. See to L<convert_blessed>.
1757
1758					=item $JSON::QuotApos
1759
1760					(Only with JSON::PP, if C<-support_by_pp> is not used.)
1761
1762					$json->allow_singlequote->decode($json_text)
1763
1764					=item $JSON::SingleQuote
1765
1766					Disable. C<JSON> does not make such a invalid JSON string any longer.
1767
1768					=item $JSON::KeySort
1769
1770					$json->canonical->encode($perl_scalar)
1771
1772					This is the ascii sort.
1773
1774					If you want to use with your own sort routine, check the C<sort_by> method.
1775
1776					(Only with JSON::PP, even if C<-support_by_pp> is used currently.)
1777
1778					$json->sort_by($sort_routine_ref)->encode($perl_scalar)
1779
1780					$json->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })->encode($perl_scalar)
1781
1782					Can't access C<$a> and C<$b> but C<$JSON::PP::a> and C<$JSON::PP::b>.
1783
1784					=item $JSON::SkipInvalid
1785
1786					$json->allow_unknown
1787
1788					=item $JSON::AUTOCONVERT
1789
1790					Needless. C<JSON> backend modules have the round-trip integrity.
1791
1792					=item $JSON::UTF8
1793
1794					Needless because C<JSON> (JSON::XS/JSON::PP) sets
1795					the UTF8 flag on properly.
1796
1797					# With UTF8-flagged strings
1798
1799					$json->allow_nonref;
1800					$str = chr(1000); # UTF8-flagged
1801
1802					$json_text = $json->utf8(0)->encode($str);
1803					utf8::is_utf8($json_text);
1804					# true
1805					$json_text = $json->utf8(1)->encode($str);
1806					utf8::is_utf8($json_text);
1807					# false
1808
1809					$str = '"' . chr(1000) . '"'; # UTF8-flagged
1810
1811					$perl_scalar = $json->utf8(0)->decode($str);
1812					utf8::is_utf8($perl_scalar);
1813					# true
1814					$perl_scalar = $json->utf8(1)->decode($str);
1815					# died because of 'Wide character in subroutine'
1816
1817					See to L<JSON::XS/A FEW NOTES ON UNICODE AND PERL>.
1818
1819					=item $JSON::UnMapping
1820
1821					Disable. See to L<MAPPING>.
1822
1823					=item $JSON::SelfConvert
1824
1825					This option was deleted.
1826					Instead of it, if a given blessed object has the C<TO_JSON> method,
1827					C<TO_JSON> will be executed with C<convert_blessed>.
1828
1829					$json->convert_blessed->encode($blessed_hashref_or_arrayref)
1830					# if need, call allow_blessed
1831
1832					Note that it was C<toJson> in old version, but now not C<toJson> but C<TO_JSON>.
1833
1834					=back
1835
1836					=head1 TODO
1837
1838					=over
1839
1840					=item example programs
1841
1842					=back
1843
1844					=head1 THREADS
1845
1846					No test with JSON::PP. If with JSON::XS, See to L<JSON::XS/THREADS>.
1847
1848
1849					=head1 BUGS
1850
1851					Please report bugs relevant to C<JSON> to E<lt>makamaka[at]cpan.orgE<gt>.
1852
1853
1854					=head1 SEE ALSO
1855
1856					Most of the document is copied and modified from JSON::XS doc.
1857
1858					L<JSON::XS>, L<JSON::PP>
1859
1860					C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>)
1861
1862					=head1 AUTHOR
1863
1864					Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt>
1865
1866					JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de>
1867
1868					The release of this new version owes to the courtesy of Marc Lehmann.
1869
1870
1871					=head1 COPYRIGHT AND LICENSE
1872
1873					Copyright 2005-2013 by Makamaka Hannyaharamitu
1874
1875					This library is free software; you can redistribute it and/or modify
1876					it under the same terms as Perl itself.
1877
1878					=cut
1879
1880
1881					;